MCP 서버 및 스킬 사용

오늘 다룰 업무: handstack-docs 스킬 사용

“handstack-docs의 스킬을 설치하고,
handstack-source-trace로 화면 연결 경로를 확인해 주세요.”

1. 문서 MCP를 연결해 HandStack 규칙을 찾습니다.
2. handstack-docs 스킬 번들을 프로젝트에 설치합니다.
3. 스킬을 명시 호출해 읽은 문서·파일을 확인합니다.
4. 점검기 결과와 실제 소스 확인을 나눠 봅니다.

명령과 요청을 입력하는 곳

/mcp, /스킬이름, $스킬이름, 요청 문장은 대화창에 입력합니다.
코드 블록의 # 줄은 명령의 설명 주석입니다.

MCP란 무엇인가요?

Model Context Protocol: AI 앱과 외부 도구·데이터를
연결하는 공통 통신 규약입니다.

도서관에 비유하면, AI가 사서에게 “거래 호출 규칙을 찾아 줘”라고
요청하고 사서가 문서와 출처를 돌려주는 통로입니다.

• 호스트: Claude Code·Codex 같은 AI 앱
• 클라이언트: 앱 안에서 서버와 통신하는 연결 구성 요소
• 서버: 문서 검색 등 기능을 제공하는 프로그램

문서를 찾아 답하기까지

개발자 요청 → AI 앱 → MCP 서버 → 문서 검색 결과 → AI 답변

1. 개발자: “belongID가 어떤 역할인지 찾아 줘.”
2. AI: 서버의 search_docs 도구를 선택합니다.
3. 서버: 관련 문서 위치를 반환합니다.
4. AI: get_doc으로 본문을 읽고 출처와 함께 답합니다.

모델을 새로 학습시키는 과정은 아닙니다.
필요한 정보를 작업 중에 가져옵니다.

MCP 서버가 제공할 수 있는 것

서버마다 제공 기능과 권한이 다릅니다.
이번 실습은 공개 문서를 읽는 HandStack 문서 도구를 씁니다.

MCP · 스킬 · 프로젝트 지침

스킬은 MCP 없이도 로컬 소스를 읽을 수 있습니다.
MCP를 연결하면 스킬이 필요한 문서도 조회할 수 있습니다.

원격 HTTP와 로컬 stdio

이번 실습 주소: https://handstack.kr/mcp

별도 MCP 서버 프로그램 설치나 로그인 없이 이용합니다.
로컬에서 실행하는 HTTP 서버도 URL로 연결합니다.

실습 준비

• Claude Code 또는 Codex CLI 설치·로그인
• 터미널에서 본인이 작업할 프로젝트 루트 열기
• 인터넷에서 https://handstack.kr 접근 가능
• 스킬 점검기를 쓸 경우 Python 3.10 이상
• 스킬 호출 실습: 화면·거래 계약이 있는 HandStack 프로젝트(읽기 전용 분석)

# 설치된 도구만 확인합니다.
codex --version
claude --version
python --version

Codex CLI: 문서 MCP 추가

터미널에서 실행합니다.

# 같은 사용자 계정에서 사용할 문서 서버를 등록합니다.
codex mcp add handstack-docs --url https://handstack.kr/mcp

# 등록된 서버와 상세 설정을 확인합니다.
codex mcp list
codex mcp get handstack-docs

기본 저장 위치는 사용자 홈의 ~/.codex/config.toml입니다.
이미 등록되어 있으면 get으로 확인한 뒤 관리 실습으로 넘어갑니다.

Claude Code: 문서 MCP 추가

작업할 프로젝트 루트의 터미널에서 실행합니다.

# 이 프로젝트에서 개인적으로 사용할 연결을 등록합니다.
claude mcp add --transport http --scope local handstack-docs https://handstack.kr/mcp

# 등록과 연결 상태를 확인합니다.
claude mcp list
claude mcp get handstack-docs

local 범위는 등록한 프로젝트에서만 사용합니다.
다른 프로젝트에서도 쓰려면 user 범위를 선택합니다.

등록 다음에는 실제 호출 확인

1. 설정을 반영할 새 대화 세션을 엽니다.
2. 대화창에서 /mcp로 서버·도구 상태를 봅니다.
3. 아래 요청을 보내고 도구 호출 기록을 확인합니다.

handstack-docs MCP의 search_docs로 belongID를 찾아 줘.
찾은 문서를 get_doc으로 읽고, 역할과 문서 URL을 알려 줘.
도구를 쓸 수 없다면 그 상태를 먼저 알려 줘.

목록에 등록됨 → 연결됨 → 검색·본문 조회 성공을 구분합니다.

HandStack 문서 MCP의 도구

먼저 핵심 단어로 검색하고 필요한 본문만 읽습니다.
질문에 맞는 도구가 호출됐는지도 확인합니다.

문서 검색을 스킬 요청으로 이어 가기

handstack-docs MCP로 reference/식별자와-파일-경로를 읽어 줘.
ServiceID와 statement id가 어떤 역할인지 문서 URL과 함께 알려 줘.
내 프로젝트에서 이 규칙을 확인할 수 있는 파일 후보를 찾아 줘.
문서와 실제 코드가 다르면 각각의 근거를 보여 줘.
지금은 파일을 수정하지 마.

확인할 결과: 문서 URL + 규칙 요약 + 실제 파일 경로

문서 MCP는 내 PC의 소스·DB를 자동으로 읽지 않습니다.
로컬 소스는 코딩 도구의 파일 읽기 기능으로 확인합니다.

팀 공유: Claude Code

프로젝트 루트의 **.mcp.json**에 넣는 최소 예입니다.

{
  "mcpServers": {
    "handstack-docs": {
      "type": "http",
      "url": "https://handstack.kr/mcp"
    }
  }
}

기존 파일에는 해당 서버 항목만 병합합니다.
대화형 실행에서 프로젝트 MCP 사용 승인이 표시될 수 있습니다.

팀 공유: Codex CLI

신뢰한 프로젝트의 **.codex/config.toml**에 넣는 예입니다.

[mcp_servers.handstack-docs]
url = "https://handstack.kr/mcp"

• 기존 TOML에 같은 테이블을 두 번 만들지 않습니다.
• 개인 설정에 같은 서버가 있으면 중복·우선순위를 확인합니다.
• 팀 공유 파일에는 비밀 토큰을 넣지 않습니다.
• 프로젝트 신뢰·관리자 정책에 따라 로드가 제한될 수 있습니다.

주소나 설정을 변경할 때

1. mcp get handstack-docs로 현재 주소·범위를 기록합니다.
2. 설정 파일을 백업하고 해당 서버 항목만 수정합니다.
3. 새 세션에서 목록·연결·실제 검색을 다시 확인합니다.

Claude: .mcp.json 또는 ~/.claude.json의 해당 항목
Codex: 사용자 또는 프로젝트 config.toml의 해당 테이블

CLI로 재등록할 때는 기존 범위에서 제거 → 새 주소로 추가합니다.
주소 변경으로 인증이 달라지면 서버 안내에 따라 다시 인증합니다.

MCP 삭제: 연결 등록 해제

이 서버의 도구를 더 이상 사용할 수 없게 됩니다.
다음은 앞에서 CLI로 등록한 범위를 제거하는 명령입니다.

# Claude: 앞 실습의 local 등록을 제거합니다.
claude mcp remove handstack-docs --scope local
claude mcp list

# Codex: 사용자 설정의 등록을 제거합니다.
codex mcp remove handstack-docs
codex mcp list

공유 파일·다른 범위에 남은 항목도 확인합니다.
외부 서버의 프로그램·데이터를 삭제하는 명령은 아닙니다.

삭제 실습 후 다시 연결하기

이후 HandStack 실습을 계속하려면 본인의 도구 하나로
문서 MCP를 다시 등록합니다.

# Codex CLI: 사용자 범위
codex mcp add handstack-docs --url https://handstack.kr/mcp

# Claude Code: 개발 프로젝트 루트에서 local 범위
claude mcp add --transport http --scope local handstack-docs https://handstack.kr/mcp

새 대화에서 /mcp를 열고 belongID 검색을 다시 요청합니다.
삭제 후에도 스킬 파일은 남으며, MCP는 따로 다시 연결해야 합니다.

잠시 끄기와 다시 켜기

Codex: 기존 서버 테이블에 enabled 값을 추가·수정합니다.

[mcp_servers.handstack-docs]
url = "https://handstack.kr/mcp"
enabled = false

다시 켤 때는 true로 바꾸고 새 세션에서 확인합니다.
Claude: /mcp에서 해당 서버의 활성·비활성 메뉴를 확인합니다.
메뉴·지원 범위는 설치된 버전의 도움말을 따릅니다.

“갱신”할 대상을 구분하세요

HandStack 문서 서버는 기본적으로 10분마다 인덱스를 다시 읽습니다.
같은 URL의 문서 갱신에 매번 서버를 재등록할 필요는 없습니다.

인증이 필요한 다른 MCP 서버

• 공개 HandStack 문서 서버: 별도 로그인 없음
• 회사 문서·이슈·DB 서버: 계정과 접근 권한이 필요할 수 있음
• OAuth 서버: 도구의 로그인 흐름으로 계정 연결
• 토큰 방식: 비밀 값은 환경 변수·안전한 자격 증명 저장소 사용

Codex의 지원 명령은 codex mcp login --help로 확인합니다.
Claude는 /mcp의 해당 서버에서 인증 안내를 확인합니다.

서버 등록, 계정 로그인, 읽기·쓰기 권한은 각각 확인합니다.

스킬은 어떻게 동작하나요?

작업에 맞는 지침과 자료를 묶은 폴더입니다.

handstack-source-trace/
  SKILL.md          언제 쓰고 어떤 순서로 확인할지
  scripts/          연결표 점검 스크립트
  references/       점검 결과 해설
  agents/           Codex용 메타데이터

이름·설명을 보고 선택한 뒤 상세 지침을 읽습니다.
스킬의 지침과 함께 실행할 스크립트의 내용·영향도 확인합니다.

HandStack 작업별 스킬 선택

첫 실습에는 추적 스킬과 문제 진단 스킬을 사용합니다.
전체 목록과 설치기는 스킬 목록과 설치에서 확인합니다.

스킬 원본 준비

1. HandStack 스킬 ZIP을 내려받아 새 폴더에 풉니다.
2. Install-Skills.ps1과 skills/ 폴더가 있는지 확인합니다.
3. 터미널에서 설치기가 있는 폴더로 이동합니다.

# 아래 경로를 실제 압축 해제 위치로 바꾸세요.
Set-Location C:\work\handstack-developer-skills
Get-ChildItem .\Install-Skills.ps1, .\skills

ZIP을 받을 수 없으면 저장소의 agent-skills를 받습니다.
설치 폴더와 개발할 프로젝트 폴더를 구분하세요.

설치 위치와 확인

# 앞 슬라이드에서 지정한 프로젝트의 설치 결과를 확인합니다.
Get-ChildItem "$ProjectRoot/.claude/skills" -Directory
Get-ChildItem "$ProjectRoot/.agents/skills" -Directory
Set-Location $ProjectRoot

처음에는 한 범위를 선택하세요. 설치 후 새 대화에서 확인합니다.

스킬을 명시해서 요청하기

Claude Code · Codex CLI 공통 대화창

handstack-source-trace 스킬로 이 프로젝트의 조회 화면 하나를 골라
버튼에서 SQL까지 추적해 줘.
handstack-docs MCP로 관련 문서도 읽어 줘. 파일은 수정하지 마.

요청에 스킬 이름을 글로 적으면 두 도구에서 같은 문장을 씁니다.
사용한 스킬과 읽은 파일·문서가 답변에 드러나는지 확인합니다.

선택: Claude는 /스킬이름, Codex는 $스킬이름으로도 지정할 수 있습니다.

스킬 갱신: 새 원본으로 교체

기존 설치 내용이 교체됩니다. 새 ZIP은 별도 폴더에 풉니다.
그 폴더에서 앞과 같은 대상 경로·스킬 목록을 지정합니다.

# 실제 새 ZIP 압축 해제 위치로 이동합니다.
Set-Location C:\work\handstack-developer-skills-new

# 앞에서 정의한 $ProjectRoot와 $Skills를 그대로 사용합니다.
.\Install-Skills.ps1 -Tool Both -Scope Project `
  -ProjectRoot $ProjectRoot -Skill $Skills -Update -WhatIf
.\Install-Skills.ps1 -Tool Both -Scope Project `
  -ProjectRoot $ProjectRoot -Skill $Skills -Update

다른 내용은 -Update 없이 덮어쓰지 않습니다.
기존 파일은 .claude/skills-backup/·.agents/skills-backup/에 보관됩니다.

스킬을 사용하지 않게 하기

해당 범위의 스킬 폴더 전체를 백업한 뒤
검색 경로 밖으로 이동하면 활성 목록에서 제외할 수 있습니다.

예: .agents/skills/handstack-source-trace를
프로젝트의 .agents/skills-backup/수동보관/ 아래로 옮깁니다.

• Claude도 설치했다면 .claude/skills/ 쪽을 따로 확인합니다.
• 사용자 범위나 플러그인에도 같은 이름이 있는지 확인합니다.
• 새 세션에서 목록·호출 가능 여부를 다시 확인합니다.
• MCP 연결은 별도 설정이므로 그대로 남습니다.

사례 1: 설치한 스킬 읽어 보기

스킬은 SKILL.md의 이름·설명을 보고 선택됩니다.
설치한 스킬이 언제 쓰이고 무엇을 하는지 먼저 읽습니다.

handstack-source-trace 스킬의 SKILL.md를 읽고
어떤 요청에 쓰는 스킬인지 요약해 줘.
점검기가 코드·SQL을 실행하는지, 어떤 파일을 읽는지도 알려 줘.
파일을 수정하거나 스크립트를 실행하지 마.

예상 결과: 사용 시점 + 읽기 전용 점검기라는 설명 + 읽은 파일 경로

사례 2: 점검기로 화면 목록 확인

handstack-source-trace 스킬로 점검기의 --list를 실행해
이 프로젝트의 화면 ID 목록을 보여 줘.
그중 조회 화면 하나를 골라 --screen으로 연결표를 만들어 줘.
서비스 ID, 입력 필드, SQL 파라미터, 출력 순서를 표로 써 줘.
파일을 수정하거나 거래·SQL을 실행하지 마.

예상 결과: 화면 ID 목록 + 서비스 | 입력 | 출력 순서 | 실행 | callback 연결표

문서 근거와 로컬 구현 근거를 함께 읽습니다.

점검기 출력은 이렇게 읽습니다

불일치 후보는 정규식 기반 근사치입니다.
ERROR도 소스를 직접 열어 확정한 뒤 보고합니다.

점검기 직접 실행하기

개발 프로젝트 루트의 터미널에서 실행합니다.

# Codex 프로젝트 설치 기준입니다. Claude는 .claude/skills를 씁니다.
$SkillRoot = '.agents/skills'
python "$SkillRoot/handstack-source-trace/scripts/hs_inspect.py" --root . --list

# --list에서 확인한 화면 ID로 바꾸세요.
$ScreenId = '조회-화면-ID'
python "$SkillRoot/handstack-source-trace/scripts/hs_inspect.py" `
  --root . --screen $ScreenId --fail-on ERROR

점검기는 정적 분석의 후보를 보여 줍니다.
SQL 실행·서버 반영·브라우저 성공을 보장하지 않습니다.

결과는 세 가지로 나눠 읽습니다

비활성 코드와 실제 호출 경로를 구분합니다.
설정 파일의 키·연결 문자열은 답변에 복사하지 않게 합니다.

“스킬이 답했다”와 “업무 기능이 실행됐다”는 별개입니다.

사례 3: 스킬이 선택되지 않을 때

handstack-source-trace 스킬로 화면 목록을 보여 달라고 했는데 스킬이 사용되지 않아.
설치 경로, 스킬 폴더 이름, 사용자·프로젝트 범위의 중복 설치를 확인해 줘.
새 세션에서 목록에 보이는지도 알려 줘.
Install-Skills.ps1은 -WhatIf로만 실행하고 파일은 바꾸지 마.

확인 순서: 설치 경로 → 폴더·이름 → 중복 범위 → 새 세션 → 명시 호출
처음 어긋난 지점부터 고칩니다.

스킬 원본을 고쳤다면: 번들 검증

handstack-docs 저장소 루트의 터미널에서 실행합니다.

# 번들 검증 → 문서 경로 인용 확인 → 단위 테스트를 순서대로 실행합니다.
npm run check:agent

• 스킬의 frontmatter, 링크, 스크립트 경로를 확인합니다.
• 스킬이 인용한 docs/ 문서 ID가 실제로 있는지 확인합니다.
• 모델이 스킬을 실제로 선택하는 품질은 검증하지 않습니다.

연결 문제를 해결하는 순서

https://handstack.kr/mcp 상태 페이지가 열리는 것과
에이전트의 실제 도구 호출 성공을 구분합니다.

작업 권한과 자료의 범위

• 서버 제공자와 도구 목록을 확인하고 필요한 연결만 켭니다.
• 공개 문서 MCP에는 비밀 키·DB 연결 문자열을 보내지 않습니다.
• 파일 수정·DB 실행은 각 도구의 실제 권한에 따라 수행됩니다.
• 스킬에 적힌 지침만으로 운영 권한이 생기지 않습니다.
• 변경 요청에는 보존할 기능, 테스트 환경, 확인 기준을 적습니다.

“문서 조회 성공”과 “업무 기능 실행 성공”은 별개입니다.

직접 해 볼 과제

1. 문서 MCP로 transactionAction의 입출력 연결을 읽습니다.
2. handstack-docs 스킬 하나를 설치하고 요청에 스킬 이름을 적어 호출합니다.
3. 점검기 --list로 본인 프로젝트의 화면 하나를 골라 연결표를 만듭니다.
4. 점검기 결과를 소스와 비교해 확인한 것과 추정한 것을 나눕니다.
5. 개인 설치 스킬 하나를 백업·갱신하고 다시 호출합니다.

제출할 것: 연결표, 설치 확인 결과, 확인·추정 구분, 미확인 항목

실습 완료 확인

• [ ] 등록한 MCP를 조회하고 실제 검색·본문 조회를 수행했다.
• [ ] 추가·삭제·비활성화·갱신의 차이를 설명할 수 있다.
• [ ] 스킬 설치 위치와 호출 방법을 확인했다.
• [ ] 화면·거래·SQL의 입력·출력 연결표를 만들었다.
• [ ] 스킬이 읽은 문서·파일과 점검기 후보를 구분해 확인했다.
• [ ] 실제 실행한 검사와 실행하지 못한 항목을 구분했다.

다음 작업에서도 문서 확인 → 소스 대조 → 작은 변경 → 결과 확인을
같은 순서로 진행합니다.

관리할 때 보는 빠른 표

실제 복사할 명령은 앞의 해당 실습 슬라이드를 사용하세요.

HandStack 문서와 스킬

• AI 에이전트에 문서 연결하기: 등록·해제·도구·문제 해결
• 스킬 목록과 설치: 설치기와 작업별 스킬
• 화면에서 거래 호출하기: 입력·출력 매핑
• 식별자와 파일 경로: 화면·거래·SQL 파일과 계약 연결
• 점검 도구: hs_inspect.py 옵션과 한계
• 스킬 원본 저장소: 설치기·지침·점검기

도구별 공식 안내

• MCP 구조: 호스트·클라이언트·서버, 통신 방식
• Codex MCP: 등록·설정·인증
• Codex Skills: 탐색 경로·스킬 사용
• Claude Code MCP: 범위·관리·연결 상태
• Claude Code Skills: 설치·호출·선택 규칙

명령 예시 기준: Codex CLI 0.164.0 · Claude Code 2.1.310
공식 안내 확인일: 2026-10-26
설치 버전이 다르면 먼저 mcp --help로 지원 옵션을 확인하세요.